home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 26
/
Cream of the Crop 26.iso
/
program
/
wil4c10.zip
/
WIL4C_R.TXT
< prev
next >
Wrap
Text File
|
1997-07-26
|
51KB
|
1,862 lines
Winsock Interface Communications
Library for C/C++
(WIL4C)
REFERENCE MANUAL
Version 1.0
July 28, 1997
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1997
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
WIL4C Reference Manual Page 1
C O N T E N T S
Chapter Page
Table of Contents.............................2
WIL Functions.................................4
wilAccept..................................4
wilAskHostByAddr...........................4
wilAskHostByName...........................5
wilAskProtoByName..........................5
wilAskProtoByNumber........................6
wilAskServByName...........................6
wilAskServByPort...........................7
wilAttach..................................7
wilAwaitEvent..............................8
wilBind....................................8
wilCancelBlocking..........................9
wilCloseSocket.............................9
wilConnect.................................10
wilDataIsReady.............................10
wilDebug...................................11
wilErrorText...............................11
wilGetDescription..........................12
wilGetHostAddr.............................12
wilGetHostAlias............................13
wilGetHostDotted...........................13
wilGetHostName.............................14
wilGetMaxSockets...........................14
wilGetMyHostAddr...........................15
wilGetMyHostDotted.........................15
wilGetMyHostName...........................16
wilGetProtoName............................16
wilGetProtoNumber..........................17
wilGetServName.............................17
wilGetServPort.............................18
wilGetSystemInfo...........................18
wilGetVendorInfo...........................19
wilIsBlocking..............................19
wilIsConnected.............................20
wilIsDotted................................20
wilListen..................................21
wilLocalSockAddr...........................21
wilLocalSockPort...........................22
WIL4C Reference Manual Page 2
C O N T E N T S
(continued)
Chapter Page
wilParseDecimal............................22
wilPeekSocket..............................23
wilReadLine................................23
wilReadOOB.................................24
wilReadSocket..............................24
wilReadString..............................25
wilRelease.................................25
wilRemoteSockAddr..........................26
wilRemoteSockPort..........................26
wilSetOOB..................................27
wilSocketStatus............................27
wilTcpSocket...............................28
wilWaitLine................................28
wilWriteLine...............................29
wilWriteOOB................................29
wilWriteSocket.............................30
wilWriteString.............................30
WIL Error Codes...............................31
WIL4C Reference Manual Page 3
+-------------+-----------------------------------------------------+
| wilAccept | Accepts incoming connection. |
+-------------+-----------------------------------------------------+
SYNTAX SOCKET wilAccept(SOCKET Socket, LONG Timeout)
// Socket : Winsock socket number.
// Timeout : Timeout in milliseconds.
REMARK The wilAccept function accepts an incoming connection on a
specified socket, dequeueing the first connection request
on the listening socket, and returns a new socket which may be
used immediately to send or receive data.
wilBind and wilListen are called before wilAccept.
RETURN >0 : Socket.
< 0 : Error. See error list.
OTHER See wilBind and wilListen.
+------------------+------------------------------------------------+
| wilAskHostByAddr | Request host information from server. |
+------------------+------------------------------------------------+
SYNTAX int wilAskHostByAddr(LPSTR Name)
// Name : Host name in dotted notation format.
REMARK The wilAskHostByAddr function requests host information. After
this call returns, the wilGetHostAddr and wilGetHostName
functions can be called to get the actual host information.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilGetHostAddr and wilGetHostName.
WIL4C Reference Manual Page 4
+------------------+------------------------------------------------+
| wilAskHostByName | Request host information from server. |
+------------------+------------------------------------------------+
SYNTAX int wilAskHostByName(LPSTR Name)
// Name : Host name.
REMARK The wilAskHostByName function requests host information.
After this call returns, the wilGetHostAddr and wilGetHostName
functions can be called to get the actual host information.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilGetHostAddr and wilGetHostName.
+-------------------+-----------------------------------------------+
| wilAskProtoByName | Request protocol information. |
+-------------------+-----------------------------------------------+
SYNTAX int wilAskProtoByName(LPSTR Name)
// Name : Protocol name.
REMARK The wilGetProtoByName function requests protocol information.
After this call returns, the wilGetProtoName or
wilGetProtoNumber functions can be called to get the actual
information.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilGetProtoName and wilGetProtoNumber.
WIL4C Reference Manual Page 5
+---------------------+---------------------------------------------+
| wilAskProtoByNumber | Request protocol information. |
+---------------------+---------------------------------------------+
SYNTAX int wilAskProtoByNumber(int Number)
// Number : Protocol number.
REMARK The wilAskProtoByNumber function requests protocol
information. After this call returns, the wilGetProtoName or
wilGetProtoNumber functions can be called to get the actual
information.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilGetProtoName and wilGetProtoNumber.
+------------------+------------------------------------------------+
| wilAskServByName | Request server information. |
+------------------+------------------------------------------------+
SYNTAX int wilAskServByName(LPSTR Name, LPSTR ProtoName)
// Name : Host name.
// ProtoName : Protocol name.
REMARK The wilAskServByName function requests server information.
After this call returns, the wilGetServName or wilGetServPort
functions can be called to get the actual information.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilGetServName and wilGetServPort.
WIL4C Reference Manual Page 6
+------------------+------------------------------------------------+
| wilAskServByPort | Request server information. |
+------------------+------------------------------------------------+
SYNTAX int wilAskServByPort(int Number, LPSTR ProtoName)
// Number : Port number
// ProtoName : Protocol name.
REMARK The wilAskServByPort function requests server information.
After this call returns, the wilGetServName or wilGetServPort
functions can be called to get the actual information.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilGetServName and wilGetServPort.
+-------------+-----------------------------------------------------+
| wilAttach | Attaches (initializes) winsock. |
+-------------+-----------------------------------------------------+
SYNTAX int wilAttach(void)
REMARK The wilAttach function prepares the WIL system for processing.
This should be the first WIL function called.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilRelease.
WIL4C Reference Manual Page 7
+----------------+--------------------------------------------------+
| wilAwaitEvent | Set asynchronous event winsock mask. |
+----------------+--------------------------------------------------+
SYNTAX int wilAwaitEvent(SOCKET Socket, HWND hWnd, WORD Message,
ULONG EventMask)
// Socket : Winsock socket number.
// hWnd : Window handle for message posting.
// Message : Message number.
// EventMask : Event Mask.
REMARK The wilAwaitEvent function enables asynchronous processing by
enabling the events specified by the EventMask. Event mask
values are defined in WINSOCK.H as
FD_ACCEPT Sends message when socket has incoming connection.
FD_CLOSE Sends message when socket has been closed.
FD_CONNECT Sends message when socket has completed connecting.
FD_OOB Sends message when out-of-band data can be read.
FD_READ Sends message when data is available to read.
FD_WRITE Sends message when socket is ready for writing.
When the specified event occurs, the specified message is
posted to the specified window.
Several macros are defined for calling wilAwaitEvent. Refer to
wilAwaitConnect, wilAwaitAccept, wilAwaitRead, wilAwaitRead,
wilAwaitWrite, wilAwaitClose, and wilAwaitCancel (in WIL.H).
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilListen and wilAccept.
+-------------+-----------------------------------------------------+
| wilBind | Bind socket to specified address & port nunber. |
+-------------+-----------------------------------------------------+
SYNTAX int wilBind(SOCKET Socket, ULONG LocalAddr, short LocalPort)
// Socket : Winsock socket number.
// LocalAddr : Local socket address.
// LocalPort : Local port number.
REMARK The wilBind function binds a socket address and a port number
to a particular socket. The bind function specifies the local
interface address and port number for the specified socket.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilListen and wilAccept. Also FTP.C example program.
WIL4C Reference Manual Page 8
+-------------------+-----------------------------------------------+
| wilCancelBlocking | Cancels blocking call. |
+-------------------+-----------------------------------------------+
SYNTAX int wilCancelBlocking(void)
REMARK The wilCancelBlocking function cancels any blocking call in
progress.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilIsBlocking.
+----------------+--------------------------------------------------+
| wilCloseSocket | Close socket. |
+----------------+--------------------------------------------------+
SYNTAX int wilCloseSocket(SOCKET Socket)
// Socket : Winsock socket number.
REMARK The wilCloseSocket function closes a socket. After closing,
I/O can no longer be performed on the socket.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilTcpSocket.
WIL4C Reference Manual Page 9
+------------+------------------------------------------------------+
| wilConnect | Initiate coonection to remote port. |
+------------+------------------------------------------------------+
SYNTAX int wilConnect(SOCKET Socket, ULONG RemoteAddr,
short RemotePort)
// Socket : Winsock socket number.
// RemoteAddr : Remote socket address.
// RemotePort : Remote port number.
REMARK The wilConnect function requests connection to a remote port.
The connection does not occur before wilConnect returns.
Rather, wilIsConnected can be called to determine when the
connection is completed and ready for I/O.
wilConnect is used in client side programs, but usually not
in server side programs.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilIsConnected
+----------------+--------------------------------------------------+
| wilDataIsReady | Is socket readable (data is ready). |
+----------------+--------------------------------------------------+
SYNTAX int wilDataIsReady(SOCKET Socket, ULONG Timeout)
// Socket : Winsock socket number.
// Timeout : Timeout in milliseconds.
REMARK The wilDataIsReady function returns TRUE if data is ready for
reading on the specified socket. This function will wait up to
'Timeout' milliseconds for incoming data before returning
FALSE.
RETURN TRUE : Incoming data is ready to read.
FALSE : No incoming data is ready.
OTHER See wilIsConnected.
WIL4C Reference Manual Page 10
+----------+--------------------------------------------------------+
| wilDebug | Returns bebug value. |
+----------+--------------------------------------------------------+
SYNTAX int wilDebug(int Parm)
// Parm : Debug parameter.
REMARK In the shareware version of WIL4C, SioDebug returns the number
of seconds left before the executable times out.
wilDebug returns 0 in the registered version of WIL4C.
RETURN See above.
OTHER None.
+--------------+----------------------------------------------------+
| wilErrorText | Get text associated with error code. |
+--------------+----------------------------------------------------+
SYNTAX int wilErrorText(WORD Code, LPSTR Buffer, int Size)
// Code : Error code.
// Buffer : Buffer for error text.
// Size : Size of error text buffer.
REMARK The wilErrorText function retrives the error text associated
with the passed error code, and returns it in Buffer.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER None.
WIL4C Reference Manual Page 11
+-------------------+-----------------------------------------------+
| wilGetDescription | Get winsock description text. |
+-------------------+-----------------------------------------------+
SYNTAX LPSTR wilGetDescription(void)
REMARK The wilGetDescription function returns the winsock
description text after initializing (by calling wilAttach).
The text returned is determined by the implementor of the
WINSOCK.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilGetVendorInfo and wilGetSystemInfo.
+----------------+--------------------------------------------------+
| wilGetHostAddr | Get host address. |
+----------------+--------------------------------------------------+
SYNTAX ULONG wilGetHostAddr(int Index)
// Index : Host address index.
REMARK The wilGetHostAddr function returns the host address,
associated with the last call to wilAskHostByName or
wilAskHostByAddr.
The first (or only) host address corresponds to Index=0.
Additional host addresses are returning for Index>0. No more
host addresses are available when 0 is returned.
See HOST.C for an example.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilAskHostByName and wilAskHostByAddr.
WIL4C Reference Manual Page 12
+-----------------+-------------------------------------------------+
| wilGetHostAlias | Get host name alias. |
+-----------------+-------------------------------------------------+
SYNTAX LPSTR wilGetHostAlias(int Index)
// Index : Host alias (address) index.
REMARK The wilGetHostAlias function returns the host alias name
associated with the last call to wilAskHostByName or
wilAskHostByAddr. The first (if any) name alias corresponds to
Index=0. No more host aliases are available when NULL is
returned.
See HOST.C for an example.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilAskHostByName and wilAskHostByAddr.
+------------------+------------------------------------------------+
| wilGetHostDotted | Get host dotted address. |
+------------------+------------------------------------------------+
SYNTAX LPSTR wilGetHostDotted(int Index)
// Index : Host address index.
REMARK The wilGetHostDotted function returns the host address in
dotted decimal notation associated with the last call to
wilAskHostByName or wilAskHostByAddr.
The first (or only) host address corresponds to Index=0.
Additional host addresses are returning for Index>0. No more
host addresses are available when 0 is returned.
See HOST.C for an example.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilAskHostByName and wilAskHostByAddr.
WIL4C Reference Manual Page 13
+----------------+--------------------------------------------------+
| wilGetHostName | Get host name. |
+----------------+--------------------------------------------------+
SYNTAX LPSTR wilGetHostName(void)
REMARK The wilGetHostName function returns the host address name
associated with the last call to wilAskHostByName or
wilAskHostByAddr.
See HOST.C for an example.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilAskHostByName and wilAskHostByAddr.
+------------------+------------------------------------------------+
| wilGetMaxSockets | Get maximum number of sockets supported. |
+------------------+------------------------------------------------+
SYNTAX int wilGetMaxSockets(void)
REMARK The wilGetMaxSockets functions the maximum number of sockets
available to the callng application.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER None.
WIL4C Reference Manual Page 14
+------------------+------------------------------------------------+
| wilGetMyHostAddr | Get local host address. |
+------------------+------------------------------------------------+
SYNTAX ULONG wilGetMyHostAddr(int Index)
// Index : Local host address index.
REMARK The wilGetMyHostAddr function returns the address of the local
host (in host byte order). The first (or only) host address
corresponds to Index=0. No more host addresses are available
when 0 is returned.
RETURN > 0 : Host address [host byte order].
< 0 : Error. See error list.
OTHER See wilGetMyHostDotted and wilGetMyHostName.
+--------------------+----------------------------------------------+
| wilGetMyHostDotted | Get local host (dotted) address. |
+--------------------+----------------------------------------------+
SYNTAX LPSTR wilGetMyHostDotted(int Index)
// Index : Local host address index.
REMARK The wilGetMyHostDotted function returns the host name of the
local host in dotted decimal notation. The first (or only)
host address corresponds to Index=0. No more host addresses
are available when NULL is returned.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilGetMyHostName and wilGetMyHostAddr.
WIL4C Reference Manual Page 15
+------------------+------------------------------------------------+
| wilGetMyHostName | Get local host name. |
+------------------+------------------------------------------------+
SYNTAX LPSTR wilGetMyHostName(void)
REMARK The wilGetMyHostName function returns the name of the local
host.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilGetMyHostAddr and wilGetMyHostDotted.
+-----------------+-------------------------------------------------+
| wilGetProtoName | Get protocol name. |
+-----------------+-------------------------------------------------+
SYNTAX LPSTR wilGetProtoName(void)
REMARK The wilGetProtoName function returns the protocol name
associated with the last call to wilAskProtoByName or
wilAskProtoByNumber.
See HOST.C for an example.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilAskProtoByName and wilAskProtoByNumber.
WIL4C Reference Manual Page 16
+-------------------+-----------------------------------------------+
| wilGetProtoNumber | Get protocol number. |
+-------------------+-----------------------------------------------+
SYNTAX short wilGetProtoNumber(void)
REMARK The wilGetProtoNumber function returns the protocol number
associated with the last call to wilAskProtoByName or
wilAskProtoByNumber.
See HOST.C for an example.
RETURN > 0 : Protocol number.
< 0 : Error. See error list.
OTHER See wilAskProtoByName and wilAskProtoByNumber.
+----------------+--------------------------------------------------+
| wilGetServName | Get server name. |
+----------------+--------------------------------------------------+
SYNTAX LPSTR wilGetServName(void)
REMARK The wilGetServName function return the server name after
associated with the last call to wilAskServByName or
wilAskServByPort.
See HOST.C for an example.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilAskServByName and wilAskServByPort.
WIL4C Reference Manual Page 17
+----------------+--------------------------------------------------+
| wilGetServPort | Get server port. |
+----------------+--------------------------------------------------+
SYNTAX LPSTR wilGetServPort(void) /* get server port [after calling
REMARK The wilGetServPort function returns the server port associated
with the last call to wilAskServByName or wilAskServByPort.
See HOST.C for an example.
RETURN > 0 : Server port number.
< 0 : Error. See error list.
OTHER See wilAskServByName and wilAskServByPort.
+------------------+------------------------------------------------+
| wilGetSystemInfo | Get winsock system information. |
+------------------+------------------------------------------------+
SYNTAX LPSTR wilGetSystemInfo(void)
REMARK The wilGetSystemInfo function returns system WINSOCK information.
The text returned is determined by the implementor of the
WINSOCK.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilGetVendorInfo and wilGetDescription.
WIL4C Reference Manual Page 18
+------------------+------------------------------------------------+
| wilGetVendorInfo | Get winsock vendor information. |
+------------------+------------------------------------------------+
SYNTAX LPSTR wilGetVendorInfo(void)
REMARK The wilGetVendorInfo function returns vendor specific WINSOCK
information.
The text returned is determined by the implementor of the
WINSOCK.
RETURN NULL : Text not available.
Else : Pointer to text.
OTHER See wilGetDescription and wilGetSystemInfo.
+---------------+---------------------------------------------------+
| wilIsBlocking | Is winsock currently blocking ? |
+---------------+---------------------------------------------------+
SYNTAX int wilIsBlocking(void)
REMARK The wilIsBlocking function returns TRUE or FALSE to indicate
if the socket is currently blocking.
RETURN TRUE : Socket is currently blocking.
FALSE : Socket is not blocking.
OTHER See wilCancelBlocking.
WIL4C Reference Manual Page 19
+----------------+--------------------------------------------------+
| wilIsConnected | Is socket connected to remote ? |
+----------------+--------------------------------------------------+
SYNTAX int wilIsConnected(SOCKET Socket, ULONG Timeout)
// Socket : Winsock socket number.
// Timneout : Timeout in millisecs.
REMARK The wilIsConnected function returns TRUE or FALSE to indicate
if the specified socket is writable, which means that a
connection has been completed to a remote host. This function
will wait up to 'Timeout' milliseconds for a connection before
returning FALSE.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilDataIsReady.
+-------------+-----------------------------------------------------+
| wilIsDotted | Is dotted string properly formed ? |
+-------------+-----------------------------------------------------+
SYNTAX int wilIsDotted(LPSTR Name)
// Name : Host name in dotted notation.
REMARK The wilIsDotted function returns TRUE or FALSE to indicate if
the passed text Name is in legal dotted format.
A legal dotted name consists of 4 components separated by
decimal points each of which is in the ranger of 0 to 255.
RETURN TRUE : Name is good dotted address.
FALSE : Name has errors.
OTHER None.
WIL4C Reference Manual Page 20
+-----------+-------------------------------------------------------+
| wilListen | Listen for incoming connection attempts. |
+-----------+-------------------------------------------------------+
SYNTAX int wilListen(SOCKET Socket, int BackLog)
// Socket : Winsock socket number.
// BackLog : Number of concurrent sessions.
REMARK The wilListen function specifies the socket to be used to
listen for incoming connection requests. A call to wilListen
is usually preceeded by a call to wilBind.
After calling wilListen, incoming connection requests can be
accepted by wilAccept.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilBind and wilAccept.
+------------------+------------------------------------------------+
| wilLocalSockAddr | Get local sock address for connected socket. |
+------------------+------------------------------------------------+
SYNTAX ULONG wilLocalSockAddr(SOCKET Socket)
// Socket : Winsock socket number.
REMARK The wilLocalSockAddr function returns the local socket address
associated with an open socket.
RETURN > 0 : Local socket address.
< 0 : Error. See error list.
OTHER See wilLocalSockPort.
WIL4C Reference Manual Page 21
+------------------+------------------------------------------------+
| wilLocalSockPort | Get local sock port number for connected sock. |
+------------------+------------------------------------------------+
SYNTAX short wilLocalSockPort(SOCKET Socket)
// Socket : Winsock socket number.
REMARK The wilLocalSockPort function returns the local socket port
associated with an open socket.
RETURN > 0 : Local socket port number.
< 0 : Error. See error list.
OTHER See wilLocalSockAddr.
+-----------------+-------------------------------------------------+
| wilParseDecimal | Parse decimal response code. |
+-----------------+-------------------------------------------------+
SYNTAX ULONG ParseDecimal(LPSTR Buffer)
// Buffer : Text buffer to parse.
REMARK The wilParseDecimal function parses the text string in Buffer
and returns the decimal value. A zero is retuned if the text
string does not begin with a decimal digit.
The function is used to return the decimal result codes
preceeding many protocol response messages, and to return the
(unsigned long) article numbers in NTTP.
RETURN Unsigned long decimal value.
OTHER None.
WIL4C Reference Manual Page 22
+---------------+---------------------------------------------------+
| wilPeekSocket | Peek into socket. |
+---------------+---------------------------------------------------+
SYNTAX int wilPeekSocket(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilPeekSocket function performs a non-destructive read or
"look ahead".
RETURN = 0 : Data not available.
> 0 : Number of bytes actually read.
< 0 : Error. See error list.
OTHER See wilReadSocket.
+-------------+-----------------------------------------------------+
| wilReadLine | Read line terminated with linefeed. |
+-------------+-----------------------------------------------------+
SYNTAX int wilReadLine(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilReadLine function reads the requested number of bytes
or until a linefeed ('\n') character is read.
Upon return, the last character of Buffer can be examined to
see if an entire line was read. Do not assume that an entire
line was read without checking that the last character is a
linefeed ('\n').
RETURN = 0 : Data not available.
> 0 : Number of bytes actually read.
< 0 : Error. See error list.
OTHER See wilReadSocket and wilReadString.
WIL4C Reference Manual Page 23
+------------+---------+--+-----------------------------------------+
| wilReadOOB | Read Out|Of|Bound data. |
+------------+---------+--+-----------------------------------------+
SYNTAX int wilReadOOB(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilReadOOB function reads the specified number of
Out-Of-Bounds (OOB) bytes for the socket. The function will
return 0 if no bytes are currently available. Note that fewer
bytes may be read than requested.
Reading of OOB data must be enabled (wilSetOOB) before calling
this function.
RETURN = 0 : Data not available.
> 0 : Number of bytes actually read.
< 0 : Error. See error list.
OTHER See wilReadSocket and wilReadString.
+---------------+---------------------------------------------------+
| wilReadSocket | Read from socket. |
+---------------+---------------------------------------------------+
SYNTAX int wilReadSocket(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilReadSocket function reads the specified number of bytes
for the socket. The function will return 0 if no bytes are
currently available. Note that fewer bytes may be read than
requested.
RETURN = 0 : Data not available.
> 0 : Number of bytes actually read.
< 0 : Error. See error list.
OTHER See wilReadLine and wilReadString.
WIL4C Reference Manual Page 24
+---------------+---------------------------------------------------+
| wilReadString | Read string from socket. |
+---------------+---------------------------------------------------+
SYNTAX int wilReadString(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilReadString function performs a wilReadSocket, then
appends the NUL character '\0'.
RETURN = 0 : Data not available.
> 0 : Number of bytes actually read.
< 0 : Error. See error list.
OTHER See wilReadSocket and wilReadLine.
+------------+------------------------------------------------------+
| wilRelease | Release (free) winsock. |
+------------+------------------------------------------------------+
SYNTAX int wilRelease(void)
REMARK The wilRelease function releases the WINSOCK resources, after
which socket functions should not be called.
wilRelease should be called before exiting the application
program.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilAttach.
WIL4C Reference Manual Page 25
+-------------------+-----------------------------------------------+
| wilRemoteSockAddr | Get remote sock address for connected socket. |
+-------------------+-----------------------------------------------+
SYNTAX ULONG wilRemoteSockAddr(SOCKET Socket)
// Socket : Winsock socket number.
REMARK The wilRemoteSockAddr function returns the address of the
connected remote socket.
RETURN Remote socket address [host byte order].
= 0 : Address not available.
OTHER See wilRemoteSockAddr.
+-------------------+-----------------------------------------------+
| wilRemoteSockPort | Get remote port number for connected socket. |
+-------------------+-----------------------------------------------+
SYNTAX short wilRemoteSockPort(SOCKET Socket)
// Socket : Winsock socket number.
REMARK The wilRemoteSockPort function returns the port number of the
cvonnected remote host.
RETURN Port number of remote socket.
= 0 : Port not available.
OTHER See wilRemoteSockAddr.
WIL4C Reference Manual Page 26
+-----------+---------+--+------------------------------------------+
| wilSetOOB | Sets Out|Of|Bound (OOB) data state. |
+-----------+---------+--+------------------------------------------+
SYNTAX int wilSetOOB(SOCKET Socket, int StateFlag)
// Socket : Winsock socket number.
// StateFlag : Enable OOB if TRUE.
REMARK The wilSetOOB function enables or disable Out-Of-Bound (OOB)
data depending on the value StateFlag.
OOB data is data that is processed ahead of any other data
that is not OOB. Typically, OOB data is used to indicate an
error condition of some sort.
When OOB is enabled, only OOB data can be read.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilReadOOB and wilWriteOOB.
+-----------------+-------------------------------------------------+
| wilSocketStatus | Get socket read/write status. |
+-----------------+-------------------------------------------------+
SYNTAX int wilSocketStatus(SOCKET Socket, int StatusFlag)
// Socket : Winsock socket number.
// StatusFlag : Status type requested (see below).
REMARK The wilSocketStatus function returns the socket status
requested as follows:
StatusFlag Description
WIL_READ_STATUS Returns TRUE if socket has incoming data.
WIL_WRITE_STATUS Returns TRUE if socket is writtable.
WIL_ERROR_STATUS Returns TRUE if socket has error.
A socket is connected if it is writtable.
RETURN WIL_NO_ERROR : No error.
< 0 : Error. See error list.
OTHER See wilDataIsReady and wilIsConnected.
WIL4C Reference Manual Page 27
+--------------+----------------------------------------------------+
| wilTcpSocket | Create TCP socket. |
+--------------+----------------------------------------------------+
SYNTAX SOCKET wilTcpSocket(void)
REMARK The wilTcpSocket function creates a TCP socket. wilTcpSocket
must be called before calling wilBind or wilConnect.
RETURN > 0 : TCP socket.
< 0 : Error. See error list.
OTHER See wilCloseSocket.
+-------------+-----------------------------------------------------+
| wilWaitLine | Read line, waiting for terminating linefeed. |
+-------------+-----------------------------------------------------+
SYNTAX int wilWaitLine(SOCKET Socket, LPSTR Buffer,
int BufSize, ULONG Timeout)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilWaitLine function reads the requested number of bytes
or until a linefeed ('\n') character is read.
The wilWaitLine function will wait up to a maximum of 'Timeout'
milliseconds for a terminating linefeed ('\n') character.
Examine the last byte of 'Buffer' to determine if the linefeed
was actually read.
RETURN = 0 : Data not available.
> 0 : Number of bytes actually read.
< 0 : Error. See error list.
OTHER See wilReadLine.
WIL4C Reference Manual Page 28
+--------------+----------------------------------------------------+
| wilWriteLine | Write linefeed terminated line to socket. |
+--------------+----------------------------------------------------+
SYNTAX int wilWriteLine(SOCKET Socket, LPSTR String)
// Socket : Winsock socket number.
// String : String buffer.
REMARK The wilWriteLine function performs wilWriteString, then
writes carriage return ('\r') and linefeed ('\n') to the
socket.
RETURN = 0 : Could not write.
> 0 : Number of bytes actually written.
< 0 : Error. See error list.
OTHER See wilWriteSocket and wilWriteString.
+-------------+----------+--+---------------------------------------+
| wilWriteOOB | Write Out|Of|Bounds (OOB) data to socket. |
+-------------+----------+--+---------------------------------------+
SYNTAX int wilWriteOOB(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilWriteOOB function attempts to write the requested
bytes in Buffer to the secified socket.
RETURN = 0 : Could not write.
> 0 : Number of bytes actually written.
< 0 : Error. See error list.
OTHER
WIL4C Reference Manual Page 29
+----------------+--------------------------------------------------+
| wilWriteSocket | Write buffer to socket. |
+----------------+--------------------------------------------------+
SYNTAX int wilWriteSocket(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket : Winsock socket number.
// Buffer : Data buffer.
// BufSize : Size of data buffer.
REMARK The wilWriteSocket function attempts to write the requested
number of byte to the specified socket.
Note that fewer bytes may be written than requested.
RETURN = 0 : Could not write.
> 0 : Number of bytes actually written.
< 0 : Error. See error list.
OTHER
+----------------+--------------------------------------------------+
| wilWriteString | Write string to socket. |
+----------------+--------------------------------------------------+
SYNTAX int wilWriteString(SOCKET Socket, LPSTR String)
// Socket : Winsock socket number.
// String : String buffer (terminated with '\0').
REMARK The wilWriteString function performs wilWriteSocket, using the
string length of String for the requested bytes to write.
RETURN = 0 : Could not write.
> 0 : Number of bytes actually written.
< 0 : Error. See error list.
OTHER
WIL4C Reference Manual Page 30
WIL Error Codes
+---------------------+-------------------------------------------+
| WIL_NO_ERROR | No error. |
| WIL_CANNOT_COMPLY | Cannot comply. Not neccessarily an error. |
+---------------------+-------------------------------------------+
| WIL_EOF | End of file (socket has been closed). |
| WIL_IS_BLOCKING | Socket is currently blocking. |
| WIL_BAD_STATUS_FLAG | Bad status flag passed to wilSocketStatus.|
| WIL_BAD_DOTTED | Bad dotted address. |
| WIL_INVALID_SOCKET | Invalid socket nunber. |
| WIL_TIMED_OUT | Socket timed out awaiting data. |
| WIL_NO_SOCK_ADDR | Socket address pool exhausted. |
| WIL_NO_PROTOCOL | AskProtoBy* not previously called. |
| WIL_NO_SERVICE | AskServBy* not previously called. |
| WIL_NO_HOST | Error returning host information. |
| WIL_EXPIRED | The shareware version has expired. |
| WIL_ABORTED | The shareware DLL has been corrupted. |
+---------------------+-------------------------------------------+
WIL_EXPIRED can be returned only when using the shareware version.
The shareware version will "time out" after 20 minutes, limiting
execution to a maximum of twenty minutes EACH time a program is run.
An expired program can always be restarted. The wilDebug function can
be called to return the number of seconds left before expiration.
WIL_ABORTED will be returned if the DLL has been modified. You should
never get this message!
WIL4C Reference Manual Page 31
